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Welcome to the world of Z80/8080 Fortran String Handling 



You have just simplified the task of handling character 
strings in your Z80/8080 computer system environment. The 
STRING/80 Bit (tm) has been designed for high performance, 
low burden, character string handling in most Z80/8080 
microcomputers using the CP/M or CP/M-Compatible operating 
system. As a collection, these machine-language routines, 
developed in assembler language, were specifically designed 
to interface to Microsoft's Fortran. However, any language 
processor that conforms to the Microsoft convention of 
passing call parameters, may obtain direct benefit from The 
STRING/80 Bit. 



The STRING/80 
functions : 



Bit includes the following calls and 



Housekeeping Call Routines 



VER$ 
DEFD$ 



DEFS$ 



DEFT$ 



Returns a string with version 
information and copyright notice. 

Initializes a default string 
variable. This variable is a non- 
dimensional string space 80 
characters in length. 

Initializes a string variable of a 
specified length, up to 255 bytes. 
Any non-dimensional string 
variable with a length between 1 
and 255 can be initialized using 
this routine. 

Initializes multiple dimension 
string variables, such as a table 
or matrix of strings. The entry 
length of these table or matrix 
structures can be any length 
between 1 and 255 characters. 



STRIP? 



Clears a string of unwanted 
characters when the string has 
been used in reading the disk or 
console. 
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String Conversion Call Routines 



UPPER$ 



LOWER $ 



CMD$ 

MAKE$ 
MERGE $ 
RIGHT$ 

MID$ 

LEFT$ 

SV7AP$ 



Converts all alphabetic (A-Z) 
characters in the string to upper 
case characters regardless of what 
they were prior to the operation. 

Converts all alphabetic character 
in the string to lower case 
characters regardless of what they 
were prior to the operation. 

Retrieves command parameters from 
CP/M systems. The default buffer 
is located at 080 Hex. 

Makes a string variable a copy of 
another string. 

Appends a copy of one string to 
another. 

Places a copy of the rightmost 
characters of a string into 
another . 

Fills a string variable with the 
characters extracted from the 
middle of another string. 



Stores a copy of 
leftmost characters 
into another. 



the extracted 
of one string 



Swaps one string with another. 



String Handling Functions 



IEOS$ 

LEN$ 
IDEN$ 



Sets literal end of string marker 
character to be any character the 
user desires. 

Returns length of string. 

Compares two strings and returns a 
-1 if the first is less than the 
second, a zero if they are equal, 
and a +1 if the first is larger 
than the second. 
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MATCH $ 



NVAL$ 



Returns location of one string 
found within another string. 

Returns location of numeric value 
in string, and moves value to 
string buffer to allow DECODE 
conversions to be performed. 



File Handling Functions 



LOOK? 



NFORM$ 



Looks to see if a given file 
exists on a disk. The routine is 
found in the utility library. The 
Fortran source is included. 

Forms a file name into a eleven 
character string which may be used 
to open a file. 



File Handling Call Routine 



CHAIN$ 
DIR$ 



Executes any CP/M program file. 

Retrieves CP/M directory 
information. The routine is found 
in the utility library. Assembler 
source code is included. 



REN$ 



KILLS 



SELCT$ 



RESET$ 



Renames a CP/M file. The routine 
is found in the utility library. 
Fortran source code is included. 

Kills, or removes a CP/M file. 
The routine is found in the 
utility library. Fortran source 
code is included. 

Selects the current CP/M drive 
assignment. The routine is found 
in the utility library. Fortran 
source code is included. 

Performs a CP/M system reset. The 
routine is found in the utility 
library. Fortran source code is 
included. 
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System Call and Supporting Function 



CPM$ 



LOC$ 



Exercises the CP/M system calls 
under the control of the Fortran 
language. 

Determines the string location and 
generates a pointer variable that 
can be passed to CPM$. 



Chapter 2 is an overview of the structure of the 
routines, the conventions employed in their use, and the 
rules governing their use. 

Chapter 3 is an initial discussion of programming using 
the STRING/80 routines. A simple "list" program is developed 
to demonstrate the simplicity of the routines and their use. 

Chapter 4 is a discussion of the Demonstration Program 
(DEMO). Although rather simple in function, and admittedly 
contrived, this demonstration program illustrates at least 
one use of each of the STRING/80 functions in context of an 
application. 

Included in the demonstration package are several other 
simple programs that can be viewed using the list program. 
These include: 



DEMO 



LIST 



FORMAL 



SERIES 



The host program that calls each 
of the others and performs several 
management tasks such as menus in 
response to HELP, a display of 
file names in response to DIR, 
kills a file (KILL), and renames a 
file (REN) . 

A generalized list program as 
developed in the programing 
section of the manual. 

A program to reformat a Fortran 
source program and sequentially 
renumber the labels. 

A program to name and manage up to 
three numeric series, each 
containing up to seventeen entries 
each. Reporting of the individual 
series includes the entry count, 
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total value, average, minimum and 
maximum values found. 

SORT A simple sort program capable of 

sequencing a standard CP/M text 
file. A list of U.S. presidents 
in included for the demonstration. 

Each of these programs can be run "stand-alone" or as 
part of the demonstration program. 

Chapter 5 is a brief description of some advanced 
programming techniques associated with The STRING/80 Bit for 
those who are interested in going further with these 
routines. This chapter is not intended to be an exhaustive 
course, but rather a primer for those interested in exploring 
some of the subtle capabilities inherent in the STRING/80 
package. 

Chapter 6 is a complete reference section. Each routine 
is identified and the call parameter sequence is discussed. 
Unique requirements are identified, and where appropriate, 
special techniques are reviewed. 

The Appendicies contain a quick referecnce quide, 
identification of the software included on your disk, and a 
handy user comment and/or problem identification sheet. 

The STRING/80 Bit is a powerful enhancement to Fortran 
in the Z80/8080 envirnonment, especially for those using the 
CP/M system. We hope you will take your time to become 
familiar with it, use it, and appreciate it as much as we 
have. 
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Structural Overview 



Each STRING/80 Bit function or call routine works upon 
one or more character strings. The first thing you must do 
to use the STRING/80 Bit is to define the desired string 
variables in working storage and give them a name. Once this 
is done all further references can be accomplished by using 
the defined name. 



Defining a String Variable 

Before jumping headlong into the structure of the 
STRING/80 Bit, let's consider some of the general rules that 
apply to the use of all strings while in this environment. 
Perhaps not all of these rules and conventions will be 
particularly meaningful at this time, however as we proceed 
the meaning will become more clear. Once you have completed 
this section, and have examined some of the demonstration 
(DEMO) code, it is suggested that you return to this section 
and review these rules and conventions. 



Rules 



1. All character strings must be defined as BYTE, 
or character type data. 

2. The arrays defined should be large enough to 
hold the longest string of characters that will be 
moved into the string variable. This can be an 
array size of from one to 255 characters. If a 
string variable of too short a length is 
inadvertantly used, the STRING/80 Bit truncates the 
string when out of room. 

3. The valid characters in a string include 
alphabetic (upper and lower case) , numerics, all 
special characters and the TAB character. Another 
way to state this for those requiring a more 
precise definition is all characters of hexidecimal 
values 20H through 7EH, and value 09H. The current 
keyboard end-of-string (EOS) character can never be 
used in a string since, by definition, it will 
terminate the string. The EOS can however be 
changed using the IEOS$ function to be any desired 
character. If a zero (binary 0) is assigned using 
IEOS$, any character may be present in the string. 
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The default keyboard EOS for the system is an- at- 
sign (@) . 

4. The maximum character string length allowable 
is 255 decimal. 

5. The character string variable name size can be 
anything between one and six characters in length. 
While this provides some flexibility, it is 
recommended than you try to keep the names as short 
as possible for sake of code clarity; but not so 
short that the meaning of the name is lost. 

6. Strings used for storing file names must be at 
least 12 characters in length. An easy way around 
having to keep track of this is to use a default 
string (length 80 characters) for this purpose. 

7. When compiling and linking Fortran programs, 
always search the UTL80.REL library (if necessary) 
before searching the STR80.REL library. 

8. The STRING/80 Bit routine CHAIN$ is not suited 
for storing in ROM memory. 

9. Mimic Fortran's use of registers when using the 
STRING/80 Bit from assembler language. 

In addition to the above rules, it is recommended that 
the following conventions be used. Some of these are 
presented to make it easier to identify what is happening in 
your code, for documentation purposes more than anything 
else. Others are presented to help you avoid some of the 
situations that can arise. While these are not mandatory, 
programming will be much easier and simplier if followed, 
especially when you first start using the STRING/80 Bit. 



Conventions 

1. String variable names should utilize the '$* as 
the last position of the name. For example, rather 
than name a string variable SAM, SAM$ is 
preferable. 

2. Use default strings whenever you can. The only 
cases not appropriate for the use of default 
strings is when a string of more than 80 characters 
is required, storage optimization is a concern, or 
when a table or matrix of strings is desired. 
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3. The String variable lengths for storage 
optimization or tables should be defined as only 
that needed. If a list of twelve character names 
is being managed for example, only twelve 
characters need be defined. 

4. Always use default strings to read data from 
the console or disk and when passing strings to the 
CP/M operating system. 

5. When control strings (defined below) are used, 
define the control string as 8 bytes in length. 

6. Change the end-of-string character (EOS$) as 
seldom as possible. 

7. Do not pass literals (i.e., 1), rather set 
variables such as N=l and pass the variable, N, in 
the parameter list. This MUST be the case for all 
parameters of the DIR$ and CPM$ statements. 

The Type of String Variables 

There are two types of character string variables that 
can be handled in the STRING/80 system, default string 
variables and control string variables. Further, string 
variables can be single strings or multiple dimension 
strings, such as tables of strings or a matrix of strings. A 
default string can only be a single string of 80 characters 
and is initialized using the DEFD$ statement. Single strings 
of lengths other than 80 characters are defined as control 
strings and are defined using the DEFS$ statement. Tables of 
strings, whether one dimension or two (matrix) , are defined 
as control strings and are defined using the DEFT$ statement. 

In summary, all strings other than the default string 
are control strings. The Default string is not dimensioned 
and has a fixed length of 80 characters. The two types of 
control strings are String, with no dimension, and Table with 
two dimensions. 



The Default String Variable 

The default string variable is provided for the common, 
and most frequent, string variable requirements. The string 
functions will treat a default string as being 80 characters 
long. Thus the default string variable takes on the 
attributes of being a single dimension string variable with a 
string length of 80 characters. 
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A default string, with the name A$ f is declared as 
follows: 

BYTE A$(80) 
CALL DEFD$(A$) 

The dollar sign symbol, while one of the six characters 
in the name, is used just as a reminder that this is the 
string name that is passed to the string routines. The 
dollar sign is not required, any valid Fortran variable name 
may be used. The benefits of using the "$" symbol will 
become apparent as we proceed. The second line, or 
initialization statement DEFD$, define default string, is 
generally found as one of the first executable statements in 
the program and is the way the default string variable is 
initialized. As a result of this action, A$ will appear to 
be an empty string; or a string of length equal to zero. 

While A$ could have been defined as less than 80 
characters there would be no protection against "over- 
running" the length if more than the defined number of 
characters were presented to it. The user, or programmer, 
must be aware of and cautious of this limitation. The safest 
way is to always declare a default string as BYTE with 80 
characters. 

It should be noted that the default string could have 
been given more than 80 characters also, however no more than 
80 would be used by the routines and thus it would only 
result in wasted memory. 

Controlled String Variables 

There are many cases when it is desirable to either 
define a string variable with a length other than 80 
characters or to define an array of string variables, such as 
a table of names. For these situations, the controlled 
string variable should be used. 

In this case, a control string is declared, preferably 
with a dollar sign in the name, and the actual data string 
containing the characters is separately declared, generally 
without the use of a dollar sign in the name. Consider an 
array of strings, each string is 32 characters in length and 
there are 20 strings in total, arranged in a multidimensional 
array 4 by 5. The DEFT$, or define table variable, is usee 
to define this item. This structure is declared as follows: 

BYTE A$(8) 

BYTE A(32,4,5) 

CALL DEFT$(A$,A,32,4,5) 
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or more typically, 



BYTE A$(8) ,A(32,4,5) 
CALL DEFT$(A$,A,32,4, 5) 



While the three dimensional Fortran array A(32,4,5) 
actually contains the two-dimensional string array 
characters, the eight byte array A$ is the array name that is 
used in conjunction with each string routine. Thus the 
actual Fortran code, whether referencing a default stLing 
variable or a controlled string variable, would be similar. 

The DEFT$ routine initializes the multi-dimensicnal 
array and links it to the "control" string. It declares a 3 
dimension array, with 32, 4 and 5 being the sizes of each 
dimension, under the name A, to be controlled by the control 
string A$ and hereafter referenced by the name A$. 

Granted, any other name could have be chosen (Sam and 
Carl for example), but for code clarity and improved 
documentation A$ and A were selected. In accordance with the 
recommended convention, names such as JOHN$ and JOHN or iJAME.'- 
and NAME will do as adequate a job. 

Here is another example of a control string variable 
declaration, this time a 50 entry table of twenty characters 
each : 

BYTE NAME$(8) ,NAME ( 20 , 50 , 1 ) 
CALL DEFT$(NAME$, NAME, 20, 50,1) 



Included in this control string class for string 
variables is the non dimensional, non 80 character type 
string variable. This type of string is defined using the 
DEFS$ statement (define string). In a simple example where 
we want to define a string to hold a file name, the 
definition would look like this: 

BYTE FILE$(8) ,FILE(12) 
CALL DEFS$(FILE$,FILE,12) 



Strictly speaking, the length of the control string need 
be only 4 bytes for a string and 8 bytes for up to a two 
dimension array. It is recommended that a convention of 
declaring . the control string as an 8 byte string always be 
followed. Please note, that in all cases except where you 
specifically choose to do byte manipulation, the control 
string (A$) is used and not the data string (A) . 

Now that we know how to define each of the three 
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essential string types (Default, String and Table), let's 
look at the rest of the statements and their syntax. 



The STR80 and UTL80 Command Syntax 

Throughout this document we will use the following 
command syntax: 

CALL NAME$(A$, [N1,N2] ,B$, [N1,N2] , [N3] f [N4] ) 

where; NAME$ - is the statement name, 

A$,B$ - are string names using the convention 

of a $ in the last position of the name 
as a reminder that this is the name use: 
when referencing string variables. 
N1,N2, 
N3,N4 - are integer value parameters 

and; [] - indicates the optional items. 

In the above example, note that when HI is required so 
is N2, while N3 or N4 are independent options. 

The STRING/80 Bit allows almost all integer parameters 
in the parameter lists to be literals, i.e., the routines do 
not change their values. The DIR$ and CPM$ routiner, are 
exceptions to this since they do change the values passed. 
However, it is still recommended that all parameters be 
specified as variables. 

The following is a list of each routine and their 
syntax. Remember that while the string library allows all 
types of string usage, the utility library requires that 
default strings only be passed. These default strings are 
shown as S$. 



Housekeeping Call Routines 

CALL VER$(A$,[N1,N2J) 

CALL DEFD$(A$) 

CALL DEFS$(A$,B$,N1) 

CALL DEFT$(A$,B$,N1,N2,N3) 

CALL STRIP$(A$,[N1,N2]) 

13 



The STRING/80 Bit USER MANUAL 

2 - General Conventions and Rules 



String Conversion Call Routines 

CALL UPPER$(A$, [N1,N2] ,B$, [N1,N2J) 
CALL LOWER$(A$, [N1,N2] ,B$, [N1,N2] ) 
CALL CMD$(A$, [N1,N2] ) 
CALL MAKE$(A$, [Nl f N2] ,B$, [N1,N2] ) 
CALL MERGE$(A$, [N1,N2] ,B$, [N1,N2] ) 
CALL MID$(A$, [N1,N2] ,B$, [N1,N2] ,N3,N4) 
CALL RIGHT$(A$, [Nl f N2] ,B$, [N1,N2] ,N3) 
CALL LEFT$(A$, [N1,N2] ,B$, [N1,N2] ,N3) 
CALL SWAP$(A$, [N1,N2] ,B$, [N1,N2]) 

String Handling Functions 

I=IEOS$(A$) 
I=LEN$(A$, [Nl] , [N2]) 
I=IDEN$(A$, [N1,N2] ,B$, [N1,N2] ) 
I=MATCH$(A$,[N1,N2] ,B$, [N1,N2] ,N3) 
I=NVAL$(A$, [N1,N2] ,B$, [N1,N2] ,N3) 

File Handling Functions 

I=LOOK$(S$) (UTL80) 

I=NF0RM$(A$,B$,N1) 
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File Handling Call Routines 



CALL CHAIN$(A$ f [Nl f N2] ) 
CALL DIR$(S$ f Nl) 
CALL REN$(S$) 



(UTL80) 
(UTL80) 



CALL KILL$(S$) 



(UTL80) 



CALL SELCT$(N1) 



CALL RESET$ 



(UTL80) 
(UTL80) 



System Call and Supporting Function 



CALL CPM$(A,BC,DE,HL) 
I=LOC$(A$ f [N1,N2] ) 



(passed parameters are 
integer values) 



In the next chapter we will begin programming with the 
STRING/80 Bit using the statement definitions presented in 
this chapter. Before proceeding, it is recommended that you 
review some of the rules and conventions discussed at the 
beginning of Chapter 2. 
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Getting Started 

In this chapter we will develop an application using the 
STRING/80 bit collection of tools. We will walk you through 
each step of the program developement to allow you to gam an 
insight into some of the capabilities and features. When 
completed you should have a software product that will serve 
you in many different capacities in the future. 

Beginning a programming project in any environment 
requires a definition of what you would like the program to 
do, a functional specification. Our project, selected for 
the purpose of demonstrating some of the programming 
techniques used when developing a program using the STRING/80 
bit, will be a LIST program. This will be a program that, 
when executed, will list the contents of any text file on the 
screen, similar to the TYPE command in the CP/M system. 
Since you will already have this capability, you are no doubt 
asking yourself, "Why do I need another?". The answer is 
simple. You would like a list program with some additional 
features not found in the typical LIST or TYPE program. 

First, let's look at the basic functional requirements. 
The most essential part of a list program is to be able to 
execute it simply. The primary design issue is to have the 
program respond to the following command: 

LIST d:nnnnnnnn.xxx 



where; d - is the drive identity, A, B, C or D. 

No specified drive will default to the 
currently assigned drive. 

nnnnnnnn - is the file name, and 

xxx - is the file extension. 



If only LIST is specified the program will respond with 
an operator prompt such as the following: 

Enter file name to be listed - 



In either case, whether a file was specified or entered 
as a result to the operator prompt, the program checks to see 
if the file exists prior to opening it, and if it does not 
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exist, prints the following message at the terminal 



*** FILE NOT FOUND *** 



In this situation, the program returns with the 
previously mentioned operator prompt. The user can now enter 
a valid file name or abort the program by entering either the 
word END or a control-C ( C) . Note however that a control-C 
returns control directly to the operating system, while END 
returns control to the LIST program. The program can now do 
an orderly abort and return control to the operating system 
or to some other program as can be seen in our next feature. 

It is desirable to have the ability to run the LIST 
program from another program and to have the LIST program 
return control to a specified program. We will develop the 
program to return control to the DEMO program for obvious 
reasons. 

That should be enough to keep it simple while at the 
same time provide additional functions not found in the 
common list program. Now let's develop the program to meet 
these objectives. 



Program Organization 



As an aid to the upcomming coding task an outline, or 
organization flow of the program, should first be considered. 
The organization of our case program is as follows: 



Housekeeping 



Program Identification 



Retrieve Command Line 



Validate File Name 



This code names the program, 
declares any data variables and 
constants required by the program 
and then initializes them. 

Any startup message or bulletin is 
printed with this code. 

The command line or parameters 
entered are retrieved from the 
operating system. 

This code checks to see that the 
file name retrieved from the 
command line is a valid file name 
for an existing file on the disk. 
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Format File Name 



Open File 

Change String Delimiter 



The now valid file 
formatted for use in 
OPEN statement. 



name is 
a Fortran 



Open the file we're going to list. 

Just before we start reading the 
text file, the end-of -st r ing 
character is changed to be a non- 
text character to prevent it's 
presence in the file from 
inadvertantly interfering with our 
task at hand. 



Read 
Write 

Prompt Operator 



Read Error Message 



End of Program 



Program Return Check 



Chain to Program 



Read and format the input string. 

Write the string out to the 
terminal. 

If an invalid file name was found 
in the Validate File Name routine, 
control is passed to this routine 
to prompt and retieve a new file 
name. 

If an error is encountered during 
a disk read, control is passed to 
this routine to print an error 
message and try reading the disk 
again. 

If during a read the end-of-file 
is encountered, control is passed 
to this routine for an orderly 
termination of the program. Any 
sign off messages are displayed 
here. If END is encountered as a 
file name after an operator 
prompt, control is passed to this 
routine rather than look for 
another file name. 

This routine, executed after the 
end of program routine, checks to 
see if control should be passed to 
another program or back to the 
operating system. 

If control should be passed to 
another program, the Program 
Return Check routine passes 
control to here. 



20 



The STRING/80 Bit USER MANUAL 

3 - Programming with the STRING/80 bit 

End If control should be passed to the 

operating system, the Program 
Return Check routine passes 
control here to perform that 
function. 



Now let's examine the code for each one of these 
routines individually. Once we have discussed each one 
separately, we'll look at the whole program in context. 



Housekeeping 



As in any Fortran program, the program is given a name 
and the necessary data variables are declared for subsequent 
use. In our case the program will be called LIST and the 
source code will be put in a file LIST. FOR. The standard 
editor is all that is needed to prepare the code. 

Data variables required for this program are very few. 
Three string variables are used to process the various file 
names and disk records. FILE$ was chosen as our name for the 
files string variable. It is defined as 80 characters in 
length as a Default String Variable. BUFF$ was chosen as the 
string variable for buffering the disk records prior to 
printing them at the terminal. Although this could have also 
be defined as a default string variable, for purposes of 
demonstration a Controlled String Variable was used. All 
string variables were defined as BYTE arrays. 

The default variable is initialized by DEFD$. 
Initialization for the control string is accomplished via the 
DEFS$ routine. Notice that for control strings, the 
initialization routine is the vehicle that associates the 
control string BUFF$ with the byte array BUFF. Once 
initialized all references to BUFF$, FILE$, or NAMES$ can be 
treated equivalently with the one exception of the read 
statment which we look at a little later. 



21 



The STRING/80 Bit USER MANUAL 

3 - Programming with the STRING/80 bit 

The initial code looks like the following 



PROGRAM LIST 

c 

C DEFINE STRING VARIABLES 

c 

BYTE FILE$(80) 

BYTE BUFF$(8), BUFF(80) 

BYTE NAME$(8) f NAME(12) 

c 

C INITIALIZE STRING VARIABLES 

c 

CALL DEFD$(FILE$) 

CALL DEFS$(BUFF$,BUFF,80) 

CALL DEFS$ (NAME $, NAME, 12) 

LEOS=0 



Program Identification 



It is generally a good approach for the program to 
identify itself to the user. In our case, we not only want 
to identify the program name and version information, but we 
also want to communicate the version number of the STRING/80 
bit being used in the program. An example of the type of 
message to be displayed is as follows: 

The LIST Bit (tm) - Version 1.01 
Copyright (C) 1980 Key Bits Inc. 
January, 1980 - Miami, Fl, USA 

using 

The STRING/80 Bit (tm) Version 1.16 



The code to support this includes several write 
statements, the FILE$ variable, and the VER$ call. The VER$ 
statement is to retrieve the version identification. 



22 



The STRING/80 Bit USER MANUAL 

3 - Programming with the STRING/80 bit 

c 

C PRINT PROGRAM IDENTIFICATION 

c 

WRITE(5,10) 
10 FORMAT(lX r 12X r lX) 

WRITE (5 ,20) 
20 FORMAT (IX ,12X,'The LIST Bit (tm) - Version 1.02') 

WRITE(5,30) 
30 FORMAT (1X,12X, ' Copyright (C) 1980 Key Bits Inc.') 

WRITE(5,40) 
40 FORMAT (IX, 12X f 'January, 1980 - Miami, FL, USA 1 ) 

WRITE(5,10) 

WRITE(5,50) 
50 FORMAT ( IX , 25X , ' using ' ) 

WRITE(5,10) 

CALL VER$(FILE$) 

J=LEN$(FILE$) 

WRITE(5,60) (FILE$(I) ,1=1, J) 
60 FORMAT (IX, 80 Al) 

WRITE(5,10) 

WRITE(5,10) 



The Command Line Parameter Retrieval 

When the user enters the CP/M command to execute the 
program, it is possible that he entered a string of 
characters such as the following: 

LIST TEST. FOR 



The CP/M system uses the characters 'LIST 1 to execute 
this program. It converts the string to all upper case 
characters and then leaves the residual of the command line, 
i.e. ' TEST. FOR', in the system for the programs use. Note 
that there is a leading blank in the remaining string. This 
string of characters could of course be anything, including 
nothing, and are the parameters being passed to the program. 
This data, stored at 080 Hex in the CP/M system, will 
possibly be destroyed during the execution of our program. 
As such, it is desirable to retrieve and save this 
information as early in the program as possible. The CMD$ 
call does this task. 
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c 

C RETRIEVE PARAMETERS 

c 

CALL CMD$(FILE$) 

I2=MATCH$(FILE$, •#<§', 1) 

J=LEN$(FILE$) 

IF(J.LT.2)GO TO 90 (Prompt Operator for File Name Routines) 



In this case the FILE$ string was once again used as the 
string variable in which to save our parameter information. 
Further, since there is at least one leading blank, we can 
conclude that our parameter string must be at least 2 
characters in length to be valid (blank plus 1 character). 
If it is less than 2 characters we can conclude that no file 
name parameter is present and thus go to the Prompt-Operator- 
For-File-Name routine. 



Check for Valid File Name 



If any data is found in the parameter string it is 

assumed to be a file name and must be validated. This is 

true whether we get the parameter string data from CMD$ or by 

prompting the operator to enter it (which we'll look at 

next) . The simpliest way to validate the file name is to 
look on the disk(s) and see if the file of that name exists. 
The LOOK$ function is used to do this: 



c 

C VALIDATE FILE NAME 
C 



70 CONTINUE 

I=LOOK$(FILE$) 

IF(I.GT.-l) GO TO 120 (Format File Name Routine) 

WRITE(5 f 80) 
80 FORMAT(lX f '*** FILE NOT FOUND ***») 

GO TO 90 (Prompt Operator for File Name Routine) 



As you can see from the code, the variable 'I' will 
contain a -1 if no valid file name is found or some positive 
value if it is. In this case then, if 'I' is ever greater 
than a minus one we have found a valid file name and can go 
to the Format File Name Routine. If not, we want to write a 
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"File Not Found" message to the operator and go to the Prompt 
Operator for File Name Routine. 



Prompt Operator for File Name 

If no vaild file name is found, the operator gets a 
prompt and the response is placed in the same variable, 
FILE$, as was used to store the results of the previous CMD$ 
call. 



c . 

C PROMPT OPERATOR FOR NAME 

C 

90 CONTINUE 

WRITE(5 f 100) 
100 FORMAT ( IX , 'Enter file name to be listed - ') 

READ(5,110)FILE$ 
110 FORMAT ( 80 Al) 

CALL STRIP? (FILE$) 

CALL UPPER$(FILE$) 

J=LEN$(FILE$) 

IF(J.NE.3)GO TO 70 

I=MATCH$(FILE$, , END@ , ,1) 

IF(I.GT.0)GO TO 180 (End of Program Routine) 

GO TO 70 (Validate File Name) 



The STRIP$ statement marks the end of the string. 
Fortran reads from the disk or console as if they were card 
readers with 80 positions. This means there will be trailing 
blanks. STRIP$ removes the trailing blanks and marks the end 
of the string. 

There is one other thing we need do in this routine. If 
the operator responds with the word 'END 1 or 'end', we want 
to terminate the program. After converting the FILE$ 
variable data to all upper case characters with the UPPER$ 
statement, we scan the data for a match with the MATCH$ 
statement. If a match is found the variable ■ I 1 will contain 
a value representing the location of the word 'END 1 in the 
variable FILE$. If no match is found, 'I' will contain a 
zero. 

If the variable ■ l» is greater than zero control is 
passed to the End of Program Routine. If it is zero, the 
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Check for Valid File Name Routine is executed. Notice how 
the length was tested to see if it was only three characters 
before we looked for 'END 1 . This is to avoid interpreting a 
file name such as 'SEND. TXT 1 erroneously. 

Special attention should be given to the literal ■ END@* 
in the MATCH$ statement. The at-sign within the quotes is 
the last character of any string constant. This character 
can be changed or set to a different chracter by using the 
IEOS$ function. Note however, that all string constants MUST 
be terminated by the CURRENT VALID end-of-string character. 



Format File Name, Open File f Change EOS 

The vaild file name needs to be formatted for acceptance 
by Fortran. The Microsoft compiler expects a numeric disk 
drive value (0=current, 1=A, 2=B, 3=C f 4=D) and eleven 
characters for the file name. For example, if the operator 
entered "B :TEST.FOR" as the parameter string, it need be 
converted into a variable, such as 'K', and a string 
variable, such as FILE$, wherein the new string value looks 
like "TEST FOR". The NFORM$ statement does that job for 
us. 



c ,___. 

C OPEN VALIDATED FILE NAME 
C 



120 CONTINUE 

K=NFORM$(NAME$,FILE$,l) 
CALL OPEN (7, NAME, K) 
LEOS=IEOS$(0) 



The NAME$ variable now has the formatted file name and 
'K' has the numeric drive number. The standard Fortran OPEN 
statement can now be immediately used to open the file. Note 
however that the OPEN statement uses the data string NAME and 
not the control string NAME$. 

Everything is now ready to proceed, except for one 
thing. If the list program were ever to read a copy of 
itself or read a copy of a file with an end-of-string (EOS) 
marker in it, typically an at-sign, the end-of-string 
character would terminate the line on which the EOS were 
found and thus produce invalid or truncated results. 
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in order to avoid this, we can simply reassign the value 
of the end-of-string chracter (EOS) with the IEOS? statement. 
In this case we reassigned it a numeric value zero (a .binary 
OU a character that would never show up in a string of 
characters in a text file. Now we are ready to read the 
first record. 

Read a Record From the File 

The character string variable that we decided to use for 
our buffer when reading the disk file is BUFF$. As you 
recall BUFFS is a control string that is linked to the real 
data string -BUFF via the INIT$ statement. While we could 
have defined BUFF$ to be a default string, f or P"P^ es of 
illustration we are using it in the control -String 
confiquration. Note, that had we used a default string, tne 
standard Fortran READ statement would have used BUFF$. Since 
BUFF$ is a control string, the R£ AD statement (and the WRITE 
statement) must use the real data string BUFF. This is one 
of those rare occasions when the actual string need be 

4= ^L -n- a iqn hiahliahts the value of establishing 
referenced. It also nigniigntt> uc .„„„„* „~rcnc ruff} 
consistent variable naming conventions (BUFF$ versus BUFF). 

in either case, whether a control string or default 
string, the READ statement uses the byte read format, i.e. 
80A1. 



C READ A RECORD FROM FILE 
c 



130 CONTINUE 

READ(7,140,ERR=160,END=180)BUFF 

140 FORMAT ( 80 Al) 

CALL STRIP? (BUFF$) 



Write a Record to the Screen 

The implicit DO-loop is used with the real data array to 
write the control string variable to the screen or to the 
disk in order to set the size of the string and in turn the 
fimit of" the implicit DO-loop, -J- il^l^^ ,\f t f^ f t 
the string, or buffer, BUFF$, immediately prior to writing u 

out. 
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c 

C WRITE A RECORD TO SCREEN 



C- 



J=LEN$(BUFF$) 

IF(J.LE.O) .OR.(J.GE.80)GO TO 130 
WRITE(5,150) (BUFF(I) , 1=1, J) 
150 FORMAT (IX, 80 Al) . 

GO TO 130 (Read a Record from the Disk) 



Print a Read-Error Message 

In case a read error is encountered a message will be 
printed to the operator by this routine thus letting him know 
of the event. Control will then be passed to the read 
routine to read again. No special string handl J*9 w """° 
in this routine. It's all standard Fortran. Note however 
that we could have used MAKE$ to make a st " n 9 triable such 
as MESS$, for message, contain the message and then print 
MESS$ using the write-routine. Had we, it would have looked 
like, "CALL MAKE$(MESS$,'*** READ ERROR ***(§') . However we 
didn't, so it looks like this: 



c 

C PRINT READ ERROR MESSAGE 

c 

160 CONTINUE 

WRITE(5,170) 
170 FORMAT (IX, **** READ ERROR ****) 

GO TO 130 (Read a Record from the Disk Routine) 



End of Program Routine 

When the READ statement encounters the end-of-file it 
passes control to this routine. The f iirst thing we do is 
reset the end-of-string character back to its f^f"" ***"*' 
•§• in case we want to use it in our program (which we do). 
We then print a 'Goodbye 1 message. 



28 



The STRING/80 Bit USER MANUAL 

3 - Programming with the STRING/80 bit 

c 

C END OF PROGRAM ROUTINE 

c _ 

180 CONTINUE 

LEOS=IEOS$( '§■) 

WRITE(5,10) 

WRITE(5,190) 
190 FORMAT ( IX ,12X f » Goodbye . . .*) 

WRITE(5,10) 

WRITE(5 f 10) 



Check for Return to a Program 

At this point we have the option to return to a calling 
program or the operating system. Since we will use this 
program as part of the DEMO package, for example, the same 
program can be used stand-alone or used as part of the DEMO. 
In our case the DEMO program called the LIST program and 
placed a pound-sign (#) as the last character of the 
parameter string, after a blank, and after all the data 
parameters. Thus a DEMO initited LIST would look like: 

LIST TEST. FOR # 

An operator initiated LIST would look the same but 
without the last blank and ' #'. We can now test if a '#' was 
present, the flag 12 was set in the Retrieve Parameter 
routine to reflect its presence. If present a "chain" back 
to the DEMO program will be made. If not present, control 
will go to the operating system via the normal END statement. 



c 

C CHECK FOR RETURN TO A PROGRAM 
c 

IF(I2.GT.O)GO TO 200 (Chain to Calling Program) 
GO TO 220 (Return to Operating System) 



In the next routine we need to use the standard end-of- 
string. It is IMPORTANT that the EOS be reset back to its 
default after we complete reading the disk file. 
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Chain to the Calling Program 

The CHAIN$ statement is used to call another program. 
The string name is the file name of the program followed by 
the end-of-string character, i.e. 'DEMO.COMQ' . Notice, that 
if the CHAIN$ fails, control falls through to an error 
message. This could happen if the DEMO.COM file were not 
found on the current disk, for example. 



c 

C CHAIN TO THE CALLING PROGRAM 

c 

200 CONTINUE 

CALL CHAIN$(*DEMO.COM@') 

WRITE(5,210) 
210 FORMAT ( IX, '*** DEMO.COM NOT FOUND - RETURNED TO SYSTEM ***») 



Return to Operating System 

To return to the operating system, the standard Fortran 
END statement is executed. 



c 

C RETURN TO OPERATING SYSTEM 
c 

220 CONTINUE 
END 



Summary 

You have now completed your first program using the 
STRING/80. Bit. Many of the features were used. Those that 
were not essentially work the same way. The best way to see 
this for yourself is to begin using them in you own programs, 
referring to the REFERENCE MANUAL chapter (Chapter 6) and the 
other demonstration programs for examples. Once oriented, 
these tools will vastly improve your productivity in Fortran 
and keep your string handling effort to a minimum. 
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The Whole LIST Program 

PROGRAM LIST 

c 

C DEFINE STRING VARIABLES 

C 

BYTE FILE$(80) 

BYTE BUFF$(8) , BUFF (80) 

BYTE NAME$(8) , NAME (12) 

C 

C INITIALIZE STRING VARIABLES 

C 

CALL DEFD$(FILE$) 

CALL DEFS$(BUFF$,BUFF,80) 

CALL DEFS$ ( NAME $, NAME, 12) 

LEOS=0 

c 

C PRINT PROGRAM IDENTIFICATION 

c 

WRITE(5 f 10) 
10 F0RMAT(1X,12X,1X) 

WRITE(5,20) 
20 FORMAT ( IX ,12X,' The LIST Bit (tm) - Version 1.02*) 

WRITE(5 f 30) 
30 FORMAT ( IX, 12X, 'Copyright (C) 1980 Key Bits Inc. 1 ) 

WRITE(5,40) 
40 FORMAT ( IX, 12X, 'January, 1980 - Miami, FL f USA 1 ) 

WRITE(5,10) 

WRITE (5,50) 
50 FORMAT (IX, 25X,' using') 

WRITE(5,10) 

CALL VER$(FILE$) 

J=LEN$(FILE$) 

WRITE(5,60) (FILE$(I) ,1=1, J) 
60 FORMAT (IX, 80 Al) 

WRITE(5,10) 

WRITE(5,10) 



c 

C RETRIEVE PARAMETERS 
C 



CALL CMD$(FILE$) 
I2=MATCH$(FILE$,'#@',1) 
J=LEN$(FILE$) 
IF(J.LT.2)GO TO 90 
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70 



80 



VALIDATE FILE NAME 



CONTINUE 
I=LOOK$(FILE$) 
IF(I.GT.-l) GO TO 120 
WRITE(5 r 80) 
F0RMAT(1X, '*** 
GO TO 90 



FILE NOT FOUND ***») 



PROMPT OPERATOR FOR NAME 



90 CONTINUE 

WRITE(5,100) 

100 FORMAT (IX, ' Enter file name to be listed - ') 

READ(5,110)FILE$ 
110 FORMAT ( 80 Al) 

CALL STRIP$(FILE$) 

CALL UPPER$(FILE$) 

J=LEN$(FILE$) 

IF(J.NE.3)GO TO 70 

I=MATCH$(FILE$ f ' END@ ' ,1) 

IF(I.GT.0)GO TO 180 

GO TO 70 



C OPEN VALIDATED FILE NAME 

C 

120 CONTINUE 

K=NFORM$(NAME$,FILE$,l) 
CALL OPEN (7 r NAME$, K) 
LEOS=IEOS$(0) 



C READ A RECORD FROM FILE 

c . 

130 CONTINUE 

READ (7,140, ERR=1 6 , END=1 80 ) BUFF 
140 FORMAT ( 80 Al) 

CALL STRIP$(BUFF$) 



C WRITE A RECORD TO SCREEN 

c 

J=LEN$(BUFF$) 

IF((J.LE.0) .OR.(J.GE.80)GO TO 130 
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WRITE(5 f 150) (BUFF(I) , 1=1, J) 
150 FORMAT ( IX f 80 Al) 
GO TO 130 

c . 

C PRINT READ ERROR MESSAGE 

C _ . 

160 CONTINUE 

WRITE(5 f 170) 
170 FORMAT (IX, '*** READ ERROR ***•) 

GO TO 130 

c 

C END OF PROGRAM ROUTINE 

C . _ _ 

180 CONTINUE 

LEOS=IEOS$ (•<§') 

WRITE(5,10) 

WRITE(5,190) 
190 FORMAT ( IX r 12X r ' Goodbye . . .') 

WRITE(5,10) 

WRITE(5 r 10) 

c __ __„. 

C CHECK FOR RETURN TO A PROGRAM 
c — 

IF(I2.GT.0)GO TO 200 
GO TO 220 

c _ 

C CHAIN TO THE CALLING PROGRAM 

c . 

200 CONTINUE 

CALL CHAWCDEMO.COMia 1 ) 

WRITE(5 f 210) 
210 FORMAT (IX, '*** DEMO.COM NOT FOUND - RETURNED TO SYSTEM ***§■) 

c 

C RETURN TO OPERATING SYSTEM 

c _ 

220 CONTINUE 
END 
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The Demonstration Program Functions 



The Demonstration Programs have been provided as 
examples of how various STRING/80 commands can be used in 
real case situations. All of the demonstration programs can 
be run from the program DEM0.COM. You will note that each is 
in fact a separate program in the directory. They execute 
each other by using the CHAIN$ facility found in the 
STRING/80 Bit. In addition, each can be run separately. 

The collection of demonstration programs include the 
following: 



DEMO 



A control program to run the following 
programs in a predictable and controlled 
fashion. 



LIST 



SERIES 



FORMAL 



SORT 



A program to list any file and then 
return control to the DEMO program. This 
is the same program that was developed in 
Chapter 3. 

A program to name up to three series of 
17 elements each, load, update and 
maintain the data within the series, and 
calculate the total, average, count, 
minimum, maximum of each series. Upon 
termination control is returned to the 
DEMO program. 

A program to reformat and resequence the 
numeric labels of a Fortran source 
program then return control to the 
program DEMO. 

A program to sort a list of names and 
then return control to the program DEMO. 
The demonstration file used is the 
PRES.TXT, a list of U.S. Presidents 
names in the sequence of their term in 
office. 



In addition to the collection of programs listed above, 
there are several functions contained within the main DEMO 
program worth noting. These illustrate some of the STRING/80 
commands and in particular some of the CPM$ functions. 



36 



The STRING/80 Bit USER MANUAL 
4 - The Demonstration Programs 



HELP 



This command displays a description of 
each function or command supported and a 
summary menu of all functions. 



DIRectory The currently assigned disk directory is 
displayed on the console, in bytes rather 
than Kbytes. (Record Count times 128 
bytes) 

REName The file of your choice is renamed. 

KILL The file of your choice is deleted from 
the disk directory. 



The demonstration programs are very much self 
explanatory with the possible exception of the program 
SERIES. Before providing you with a little more explanation 
on SERIES, please remember that the most effective way to get 
the feel for how each program works and its capabilities is 
to try them out. 

The SERIES program uses principles that can be put to 
use in an expanded version to make a very useful time series 
analysis and reporting system. What follows is a simple 
senario of the included SERIES program. 



COMMAND? 1=FIRST 

1 =: FIRST 
SERIES NAMES 

1 - FIRST 

2 - NO NAME 

3 - NO NAME 



FIRST is the name assigned 
to series number 1. 

The command line is echoed. 

The series names are list- 
ed to confirm action. 



COMMAND? FIRST(6)=1,2,3,4,5,6,7,8,9,8.5 The series FIRST is given 

numeric values starting in 
the 6th position. 
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COMMAND? REPORT FIRST 



Display series FIRST, 



SERIES FIRST 



1 


0.0000 


2 


0.0000 


3 


0.0000 


4 


0.0000 


5 


0.0000 


6 


1.0000 


7 


2.0000 


8 


3.0000 


9 


4.0000 


10 


5.0000 


11 


6.0000 


12 


7.0000 


13 


8.0000 


14 


9.0000 


15 


8.5000 


16 


0.0000 


17 


0.0000 


TOTAL 


53.5000 


AVERAGE 


5.3500 


COUNT 


10.0000 


MINIMUM 


1.0000 


MAXIMUM 


9.0000 


COMMAND? 





As a reminder, these demonstration programs are included 
as illustrative aids for you to follow in your use of the 
STRING/80 Bit and not necessarily here as examples of superb 
proramming techniques. In all cases, these demonstration 
programs were contrived as a platform upon which to model the 
STRING/80 Bit routines. 
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SOME ADVANCED PROGRAMMING TECHNIQUES 
CHAPTER 5 
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The Extended Capabilities of the STRING/80 Bit 

The potential capabilities of the STRING/80 Bit go 
beyond the obvious and are available to those who wish to 
perform extended string handling tasks. The objective in 
this chapter is to introduce the adventurous user to some of 
the architectural subtleties of the STRING/80 Bit. Through 
several carefully selected examples we will illustrate how 
these architectural features can be put to use. After that 
it will be up to the user to explore these advanced 
techniques using his own ingenuity. 

Essentially, the material in this chapter takes 
advantage of and builds upon the basic STRING/80 Bit 
routines, using both Fortan and assembler languages, through 
the knowledge and use of some of the inherent idiosyncrasies 
of the STRING/80 Bit design. This material will be discussed 
in the following order: 

1. The Control String Definition 

2. Manipulation of the Control String Byte(s) 

3. CP/M Calls from the Fortran Language 

4. Assemble Language use of the STRING/80 Bit 
routines. 



Some basic working knowledge of CP/M and assembler, 
although not mandatory, is assumed on behalf of the user for 
the remainder of this chapter. Those finding themselves 
uncomfortable with the material may wish to review 
Microsoft's Fortran documentation on the handling of 
registers and Digital Research's documentation on the CP/M 
architectrue. 



The Control String 

Up to now, the control string has been defined as an 
eight byte string for any control string created. This is 
not necessarily always the case. The eight bytes represent 
the maximum number of bytes required. In fact, the required 
length of the control string varies with the number of 
dimensions desired in the string array, as follows: 



40 



The STRING/80 Bit USER MANUAL 

5 - Some Advanced Programming Techniques 



String Dimensions Bytes Required 

4 
6 (not used) 



4 
none 



1 

2 8 




byte allocation is as follows: 



Byte 



Purpose 



-i String Type Designator 

9 Data String Address - Low Byte 

3 Data String Address - High Byte 

A string Length 

5 Row Address - Low Byte 

c Row Address - High Byte 

7 Column Address - Low Byte 

8 Column Address - High Byte 



. . „ „ eo hvhP 1. default strings and 

All types of strings use byte ± f u ""« ae =, <Ti-oraae 
AJ - L ^xy^ T^.Fa.,1? carinas use byte one as a storage 

control strings. Default strings use uy three. 

location of something other than a binary one f two, 

All control strings use bytes M» \'7 inqs , or tables (single 
Double dimensioned (control) strin 5 s ' or 

and double dimensioned) use bytes 1 through 8. 

~u *<: ^dqp hvtes in more detail and look at 
Let's examine each of these bytj f s in ™ 80 Bit rou tines. 
how they are used by each of the string/ bu 

Control String Byte 1 - The Data String Type Designator 

All STRING/80 routines utilize .this byte ^ ^ e ™ine 
the type of processing that^^ 
character string being reterencea. -l«<= ^ 
their meanings are as follows: 
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Byte 1 String Type Referenced 
Value 

1 A non-dimensional character string located at 
the address specified in bytes 2 and 3, with a 
length of that specified in byte 4, and 
referenced by this control string. This is 
why a non-dimensional character string 
requires a control string of four bytes. 

2 Not Used 

3 A double dimensioned character string (such as 
a matrix of names) whose first entry or string 
is located at the address specified in bytes 2 
and 3 f with each of the string entries having 
a fixed length of that specified in byte 4, 
and with the number of horizontal, or row 
entries being that specified in bytes 5 and 6, 
and with the number of vertical or column 
entries being that specified in bytes 7 and 8. 
This is why a double dimensioned character 
string requires a control string of eight 
bytes. 

0,4-255 Default String. 

From the definition of the first byte of the control string 
it should now be clear, at least preliminarily, as to the 
purpose and use of bytes 2 through 8. Let's look at each of 
them a little more closely. 

Control String Bytes 2 and 3 - The Data String Address 

The initialization routines (DEFS$,DEFT$) associate a 
control string (example, BUFF$) with a data string (example, 
BUFF) by storing the physical memory address of tne data 
string in bytes 2 and 3 of the control string. Byte 2 is the 
low address byte and byte 3 is the high address byte. 

As an example, if the data string (BUFF) were stored by 
the Fortran compiler at the physical memory address 0184 Hex 
(388 Decimal, 0000 0001 1000 0100 Binary), the value stored 
in the -second and third bytes would be 132 and l, 
respectfully. 
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Control String Byte 4 - The Data String Length 

The data string length is stored in byte 4 at the time 
of initialization by the appropriate routine. Since only 
eight bits are available in a single byte, the maximum string 
length is limited to 255 Decimal (OFF Hex f 1111 1111 Binary). 

Control String Bytes 5 and 6 - The Row Count 

The row count is stored in bytes 5 and 6 at the time of 

initilization by the appropriate "^^'^ZlTin I senate 
allow up to 65,535 decimal strings to be stored in a single 
table; more than there is memory to accomodate. 

Control String Bytes 7 and 8 - The Column Count 

The column count is stored in bytes 7 and 8 at the time 
of initialization by the appropriate routine ^se two 
bytes allow more columns than memory will permit to be stored 
in a double dimensioned string. 

Using the Control String Knowledge 

Once aware of the conrol string structure and byte 
allocation it is easy to see how this knowl edge can be p 
use First, let's look at the typical and recommended) 
method of defining and initializing a single dimensioned 
string variable (table) . 



BYTE TABLE$ (8), TABLE (13,600,1) 
CALL DEFT$ (TABLE$, TABLE, 13 ,600 , 1) 



In this example we have defined a table of 600 entries, 
having 13 characters. The physical ^ location of TABLE in 



each having __ - .. 

memory is however a function of the compiler. 
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Let us assume, for purposes of illustration, that we did 
not want to depend on the compiler to locate the table, but 
rather, we always want the table (TABLE to start at . ^ catl ™ 
E0 Hex (57344 Decimal). Implementing such a design is 
simple and straightforward. 

The byte array TABLE is NOT declared and DEFT $ is NOT 
B ~* for fhp task of initialization. Instead, simple 
a U s S s e " g nL nt statements and the STRING/80 Bit routine MAKE? xs 
used as follows: 



10 



BYTE TABLE$(8) 

TABLE$(1)=3 

TABLE$(2)=0 

TABLE$(3)=224 

TABLE$(4)=13 

TABLE$(5)=88 

TABLE$(6)=2 

TABLE$(7)=1 

TABLE$(8)=0 

DO 10 1=1,600 

CALL MAKE$(TABLE$,I,1 

CONTINUE 



(eight bytes 
(table dimens 
(location - 1 
(location - h 
(entry string 
(row count - 
(row count - 
(column count 
(column count 



needed) 
ioned string) 
ow byte - 00) 
igh byte - E0) 

length) 
low byte 88) 
high byte 512) 

- low byte 1) 

- high byte 0) 



§■) 



(null string) 



Once this has been done, ™LE$ can be referenced by 
Fortran and STRING/80 routines exactly as if ft*** *%%* 
defined by the compiler in the more traditional 
recommended method. 

Using the logic of this example, we can find many uses 
for this 'technique*. As illustrated, h h ^^ 
store a table. Another example might be that of Passing data 
between programs without having to go to disk. The data can 
now be passed via a TABLE that is physically located "above 
the highest position of the largest program in the 
participating group (remember Fortran places your Program 
q? a ck it the top of user RAM). Another case is that of 
referencing a Specific location of **l*l? B £™* hi % 
memory. And, with a little imagination, you can surely thin* 

of many more. 
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CP/M Calls from the Fortran Language 



Two special routines have been included in the STRING/80 
Bit to allow full use of the standard CP/M calls from the 
Microsoft Fortran language. These routines are: 



CPM$ 
LOC$ 



This routine is used to load the registers and pass 
the parameters to the CP/M system. 

This routine is used to locate the string address 
and create a pointer to the address that can be 
passed using the CPM$ routine. 



Perhaps the easiest way to view the operation of these 
two routines is to look at the source code of KILL$.KILL$ 
is written using Fortran, as are REN$, RESET$, SELCT$ and 
LOOK$, and utilizes the CP/M call(s) to accomplish its 
function. in the case of KILL$, the CP/M command is number 
19 or 13Hex. The file control block (FCB) address is passed 
in the DE-Register pair. The following is the total code for 
the KILL$ subroutine. 

SUBROUTINE KILL$(A$) 
INTEGER A f BC f DE,HL, DRV 
BYTE FCB$(35) 
BYTE A$(l), B$(32) 
EQUIVALENCE (B$ ( 1) , FCB$ (2) ) 

CALL DEFD(FCB$) 

CALL DEFD(B$) 

DRV=NFORM$(B$,A$ f l) 

DE=LOC$(FCB$) 

FCB$(1)=DRV 

BC=19 

CALL CPM$(A,BC,DE,HL) 

RETURN 

END 



Perhaps the only unusual technique is that of defining 
the same string space (FCB$) as both FCB$ and B$ with the 
equivalent statement. Everything else is straight forward 
and to the point. This is done so NFORM$ Places the 
formatted file name in position 2 of the file control block. 
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Ass 



embler Language use of the STRING/80 Bit Routines 



As mentioned earlier, the STRING Bit routines can be 
used by assembler, or any language that conforms to the 
Mfcrosoft Fortran convention of parameter passing. In the 
nr^ routine included in the utility library, and as used in 
til DEMO program; the STRING/80 Bit routine NFORM? is used to 

f ™k. h .<£« -"£ tlowls a partial listing of the DIR| 
mnrine only that portion dealing with the use of tne 
ou^'nFORmI. For P a complete look at the DIR$ routine 
source code use LIST to display a copy of OTL80.ASM. 



ENTRY IDIR$,DIR$ 
EXT NFORM$ 

IDIR$ is called from fortran by a call with one def ault 
string passed as a parameter. This means that the HL-Reg 
contains a pointer to the string address. We would like 
t-r, ,i=!p the l=NFORM(A$,B$,l) function to format the passea 
string to our file control block (FCB) . We can do this by 
Passing posters to the NFORM$ function in a fortran like 
manner • 

; nTR c. vra A ;ZERO A REGISTER 

IDIR$. XRA A cb+i ^^ ig the pQINTER T Q 

• THE RECEIVING STRING (A$) ^ OTrpTnM 
XCHG PLACE PASSED POINTER IN SECOND POSITION, 

XCHG '.THE DE-REG r AND THE FIRST IN THE HL-REG. 

LXI B f VALP -THIS POINTS TO THE PASSED THIRD 
LXI ' PARAMETER, THE PASSED INTEGER. 
MOV M,A PLACE A ZERO (NULL DEFAULT STRING) MARKER 

? IN OUR RECEIVING STRING (ie. A$) . 

We now look like a posible fortran like call. Remember the 
HL-Reg will return our function value, the drive number in 
our case. 

TATL NFORMS ;FILL OUR FCB WITH THE FILE NAME 
MOV A,L GET THE LOW VALUE BITS, THEY ARE ENOUGH 
' STA FCB ; PLACE THE DRIVE REQUEST VALUE 

The FCB name is now formed, we must leave a "*^ c J n ^^ n 
for the first call. DIR$ later sets this to a search next: conu 
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MVI A f 17 ;LOAD A SEARCH DIRECTORY COMMAND 

STA COMMD ;SAVE FOR LATER USE 

RET 



This concludes the discussion on some ways in which you 
can use the STRING/80 Bit routines to do more than the 
obvious. From here on it is up to you to be « ea J;*™ "J d 
reap the rewards accordingly. Best of luck; and remember, 
don't be afraid to experiment; you'll enjoy the results tor 
years to come. 
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Housekeeping Call Routines 



VERSION (VER) This routine retrieves the current version and 
copyright information on the STRING/80 Bit routines, and 
returns it in string A$. 

CALL VER$(A$, [Nl f N2]) 

A$=string 

Nl=first dimension 
N2=second dimension 

DEFINE DEFAULT STRING (DEFD) This routine initializes the 
named default string to a non-dimensional 80 character lixea 
length string variable of length zero. (Places binary zero 
in first position) 

CALL DEFD$(A$) 

A$=data array variable 

DEFINE STRING (DEFS) This routine initializes a non-default, 
non-dimensional string variable. 

CALL DEFS$(A$,B$ r Nl) 

A$=control string 
B$=data array 
Nl=length in bytes 

DEFINE TABLE (DEFT) This routine initializes tables of 
strings of one or more dimensions. 

CALL DEFT$(A$,B$,Nl,N2 f N3) 

A$=control string 
B$=data array 
Nl=length in bytes 
N2=first dimension 
N3=second dimension 
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STRIP STRING This routine strips nonrelevant characters from 
a string that has been read from the console or disk. All 
trailing blanks are suppressed. 

CALL STRIP$(A$, [N1,N2]) 

A$=the string to be stripped 
Nl=first dimension 
N2=second dimension 



String Conversion Call Routines 



UPPER This routine converts all characters in the string to 
upper case character, regardless of what they were prior to 
execution. 

CALL UPPER$(A$ f [Nl f N2] ,B$ f [N1,N2]) 

A$=first string, the string to be returned 
B$=second string, the string to be converted 
Nl=first dimension 
N2=second dimension 

LOWER This routine converts all characters in the string to 
lower case characters, regardless of what they were prior to 
execution. 

CALL L0WER$(A$,[N1,N2],B$,[N1,N2]) 

A$=first string, the string to be retruned 
B$=second string, the string to be converted 
Nl=first dimension 
N2=second dimension 

COMMAND (CMD) This routine retrieves a copy of the CP/M 
•command' line from the operating system and puts it in A?. 

CALL CMD$(A$,[N1,N2]) 

A$=string in which to store command line 
Nl=first dimension 
N2=second dimension 
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MAKE This routine makes the character string A$ equal to the 
character string B$. 

CALL MAKE$(A$, [Nl f N2] ,B$ , [Nl f N2] ) 

A$=first string, the string returned 
B$=second string, the string passed 
Nl=first dimension 
N2=second dimension 

MERGE This routine merges, or concatenates, the character 
string B$ to the end of the character string A$. 

CALL MERGE$(A$,[N1,N2],B$,[N1,N2]) 

A$=first string, the new string 
B$=second string, the string to be added 
Nl=first dimension 
N2=second dimension 

RIGHT This routine makes the character string A$ equal to the 
right N3 most number of characters of character string B$. 

CALL RIGHT$(A$,[N1,N2] ,B$ , [Nl ,N2 ] ,N3) 

A$=first string, the new string 
B$=second string, the string passed 
Nl=first dimension 
N2=second dimension 
N3=number of characters 

MIDDLE (MID) This routine makes the character string A$ equal 
to the portion of B$ that starts in position N3 and continues 
for N4 characters. 

CALL MID$(A$,[N1,N2J,B$,[N1,N2],N3,N4) 

A$=first string, the new string 
B$=second string, the string passed 
Nl=first dimension 
N2=second dimension 
N3=starting character 
N4=number of characters 
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LEFT This routine makes character string A$ equal to the left 
N3 most number of characters of the character string B$. 

CALL LEFT$(A$, [N1,N2] f B$,[Nl,N2] ,N3) 

A$=first string, the new string 
B$=second string, the string passed 
Nl=first dimension 
N2=second dimension 
N3=number of characters 



SWAP This routine swaps string A$ for string B$ and visa 
versa. 

CALL SWAP$(A$, [Nl f N2] ,B$, [N1,N2J ) 

A$=first string 
B$=second string 
Nl=first dimension 
N2=second dimension 



String Handling Functions 



INITIALIZE END OF STRING (EOS) This routine sets the end-of- 
string (EOS) character to any desired character or symbol. 
The only exclusions are that the EOS cannot be either a 
binary 1, 2, or 3. Any other binary byte between and 255 
decimal is allowed. The system keyboard default is an at- 
sign (@ a 040Hex f a 64 decimal). The value Nl is the end-of- 
string character desired and II is the value of the end-of- 
string character immediately prior to being reset to Nl . 

I1=IE0S$(N1) 

Nl=integer, set value 

Il=integer, last value 

(no string delimiter necessary) . 
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LENGTH (LEN) This routine finds the length ^character 
string A$. Note that TAB characters will be counted as ONE 
(1) character if found in the string (not 8) as will 
legitimate blanks and non-printable characters, such as the 
bell-character. II will contain the length upon return. 

I1=LEN$(A$,[N1,N2]) 

A$=string 

Nl=first dimension 
N2=second dimension 
Il=returned integer length 



IDENTICAL (IDEN) This routine compares two string. A -1 is 
returned if A$<B$, a if equal, and a +1 if A?>B^». 

I1=IDEN$(A$, [N1,N2] ,B$, [N1,N2] ) 

A$=first string 
B$=second string 
Nl=first dimension 
N2=second dimension 
Il=returned integer value 



MATCH This routine finds the first occurance of the string B$ 
in character string A$, starting in character position N3, 
and returns a zero (0) in II if not found, or returns the 
starting position of B$ (within A$) in II, if found. 

I1=MATCH$(A$, [N1,N2] ,B$, [Nl,N2] ,N3) 

A$=first string 

B$=second string 

Nl=first dimension 

N2=second dimension 

N3=starting character 

Il=returned integer position for start of match 
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NUMERIC VALUE (NVAL) This routine finds the first numeric 
value occuring after position N3 in B$ and stores it in A$. 
A decimal point is placed in position 20. The numeric value 
is centered around position 20 of A$. A$ must be at least 40 
bytes long (a default string of length 80 is recommended) . 
This function is intended to work in conjunction with DECODE. 
A$ can then be used with the FORTRAN function DECODE to 
convert characters to numerics. Upon return from the 
routine, II contains the character position immediately 
FOLLOWING the numeric value found in B$. The FORTRAN 
function ENCODE may be used to convert numerics to characters 
and place them in a byte array. 

I1=NVAL$(A$, [N1,N2] ,B$ f [Nl f N2] f N3) 

A$=first string, stored number as characters 

B$=second string, the string to be scanned 

Nl=first dimension 

N2=second dimension 

N3=starting character 

Il=returned integer value, next position 



File Handling Functions 



LOOK This routine looks for the presence of a file with the 
name as stored in the character string S$. If not found, a 
minus one (-1) is returned in II, if found a zero (0) or 
greater is returned to II. The source for this routine is 
included in the utility library. The number returned is the 
directory entry number if it exists (0 to 63) . 

Il=LOOK$(S$) 

S$=string, file name 
Il=returned integer value 



NAME FORM (NFORM) This routine formats a string into a 
legitimate file name for the Fortran language in the CP/M 
environment. 

I1=NF0RM$(A$,B$,N1) 

A$=first string, formated name returned 
B$=second string, unformated name passed 
Nl=integer, file name position in string B$ 
Il=integer, drive number 
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File Handling Call Routines 



CHAIN This routine passes control to the program name 
specified in the string variable A$. The string A$ should 
look like a command string as typed from the console, 

CALL CHAIN$(A$, [N1,N2]) 

A$=first string, file name 
Nl=first dimension 
N2=second dimension 



DIRECTORY (DIR) These routines provide the capability to 
retrieve directory information. The IDIR$ and DIR$ routines 
work together. The IDIR$ routine MUST be called first to 
intialize the retrieval sequence. The CP/M call rules apply. 
There must be no intervening disk I/O between subsequent DIR$ 
calls. A directory list for example would begin with the 
IDIR$ routine being passed a 12 character string 
????????. ???, and the DIR$ would then be called to retrieve 
each entry and its identification. The string S$ as 
recommended, should be a default string. If another type is 
selected, it should be at least 12 characters in length. 

CALL IDIR$(S$) 

S$=file search (mask) string ( 'DrAAAAAAAA.BBB' ) 



CALL DIR$(S$,N1) 

S$=string returned 
Nl=integer, returned record values 
(MUST be a variable) 
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RENAME (PEN) This routine renames a disk file. The string S$ 
is a string containing the command line as normally tound in 
the CP/M environment, i.e. NEW.TXT=OLD.TXT. This routine 
uses the CALL CPM$ routine. The source code for this routine 
is included in the utility library. 

CALL REN$(S$) 

S$=assignment string 

KILL This routine deletes, or kills, a disk file with the 

4=~„„a -: r, fho nharari-pr strina S$. This routine used the 

name found in the cnaracter btuny 09- i4ti 4.1^- rftI ,Hnp -id 

CALL CPM$ routine. The source code for this routine ib 
included in the utility library. 

CALL KILL$(S$) 

S$=assignment string 

SELECT DRIVE (SELCT) This routine selects the drive specified 

in Nl. 

CALL SELCT$(N1) 
Nl=drive number 

RESET This routine does a system reset to reinitialize the 
disk directory maps similiar to what takes place when a CTL-C 
is entered from the console. This routine used the CALL CPM? 
routine. The source code for this routine is included in the 
utlility library. 

CALL RESET$ 
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System Call and Supporting Function 



rPM This routine allows the FORTRAN user to utilize the 
^dar^caUa in the CP/M Operating ^stem by following the 
conventions specified in the Digital Research CP/M INTERFACE 
MaSuL. Specific examples of how this conunand is used ca n be 
found in Chapter 5, Some Advanced Programming Techniques. 

CALL CPM$(P1,P2,P3,P4) 

Pl=value placed in the A-register 
P2=value placed in the BC-register 
P3=value placed in the DE-register 
P4=value placed in the HL-register 

LOCATION (LOC) This routine i ^ tif ^ e \^J a OC ^ i ^ e % K l 
string and converts it to a pointer to be used by the CPM$ 

routine. 

Il=LOC$(A$,[Nl,N2]) 

A$=string 

Nl=first dimension 
N2=second dimension 
Il=pointer value 
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Software Included On The STRING/80 Bit Distribution Disk 



STR80.DOC 

STR80.REL 
UTL80.FOR 

UTL80.ASM 

UTL80.REL 
DEMO. FOR 

DEMO.COM 
FORMAL. FOR 

F0RMAL.COM 

LIST. FOR 

LIST.COM 

SERIES. FOR 

SERIES.COM 
SORT. FOR 



The STRING/80 Bit distribution disk 
documentation file listing the contents. 

The STRING/80 Bit Library 

The FORTRAN source code for selected library 
routines, namely the CALL CPM enhancement 
package. 

The Assembler source code for the DIR$ 
routine. This routine is included as part of 
the utility library. 

The Utility Library. 

The FORTRAN source code for the demonstration 
monitor program. 

The executable demonstration monitor program. 

The FORTRAN source code for the reformat and 
resequence program. This program is part of 
the demonstration package. 

The executable reformat and resequence 
program. This program is part of the 
demonstration package. 

The FORTRAN source code for the file list 
program. This program is part of the 
demonstration package. 

The executable file list program. This 
program is part of the demonstrations 
package. 

The FORTRAN source code for the series 
reporting program. This program is part of 
the demonstration package. 

The executable series reporting program. This 
program is part of the demonstration package. 

The FORTRAN source code for a simple sort 
program. This program reads standard CP/M 
text files and sequences it by individual 
line. This program is part of the 
demonstration package and uses file PRES.TXT 
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for demonstration purposes. 

S0RT.COM The executable sort program. This program is 

part of the demonstration package. 

PRES.TXT This is a text file listing the U.S. 

presidents in order of their term in office. 
This file is used by SORT in the demonstration 
package and will be converted to an 
alphabetical list of presidents names. 
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External Labels Referenced by The STRING/80 Bit Modules 

The following is a list of external entry point names 
that are referenced by some of The STRING/80 Bit library 
modules. The names should be cautiously allocated as routine 
names that will be used in conjunction with The STRING/80 Bit 
package. 



CHAIN$ CMD$ CPM$ DCODE$ DEFD$ DEFS$ DEFT$ DET$ DIR$ EOSl$ 
GET$ IEOS$ IDEN$ ITRACE$ KILL$ LEFT$ LEN$ LENl$ LOC$ LOOK$ 
LOWER$ MAKE$ MATCH$ MERGE$ MID$ MIDl$ M001$ M002$ M003$ 
M004$ M005$ NFORM$ NVAL$ POS50$ PUT$ REN$ RESET$ RIGHT$ 
RITE2$ RITE3$ R001$ R002$ R003$ R004$ R005$ R006$ R007$ 
R008$ SELCT$ STRIP$ SWAP$ T001$ T002$ T003$ T004$ T005$ 
UPPER$ VER$ 
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The STRING/80 BIT Command Quick Reference Guide 



Housekeeping Call Routines 



CALL VER$(A$, [N1,N2] ) 

CALL DEFD$(A$) 

CALL DEFS$(A$,B$,N1) 

CALL DEFT$(A$,B$ f Nl,N2 f N3) 

CALL STRIP$(A$ f [Nl f N2]) 

String Conversion Call Routines 



CALL UPPER$(A$ f [N1,N2] f B$, [N1,N2] ) 
CALL LOWER$(A$, [Nl f N2] ,B$, [N1,N2]) 
CALL CMD$(A$, [N1,N2]) 
CALL MAKE$(A$, [N1,N2] f B$ f [N1,N2]) 
CALL MERGE$(A$ r [Nl f N2] ,B$, [N1,N2] ) 
CALL RIGHT$(A$, [N1,N2] f B$ f [N1,N2] f N3) 
CALL MID$(A$, [N1,N2] ,B$, [N1,N2] f N3 f N4) 
CALL LEFT$(A$ f [Nl f N2] f B$, [Nl f N2] r N3) 
CALL SWAP$(A$ f [Nl f N2] f B$ f [Nl f N2]) 

String Handling Functions 



I=IE0S$(P1) 

I=LEN$(A$, [Nl f N2]) 

I=IDEN$(A$, [Nl f N2] f B$ f [Nl f N2] ) 

I=MATCH$(A$ r [Nl f N2] f B$ f [Nl r N2] f N3) 

I=NVAL$(A$ f [Nl f N2] f B$ r [N1,N2] ,N3) 

File Handling Functions 



# I=LOOK$(S$) 

I=NFORM$(A$ f B$ f Nl) 

File Handling Call Routines 





CALL CHAIN$(A$ f [Nl f N2]) 


+ 


CALL DIR$(S$ f Nl) 


# 


CALL REN$(S$) 


# 


CALL KILL$(S$) 


# 


CALL SELCT$(N1) 


# 


CALL RESET $ 
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System Call and Supporting Function 



CALL CPM$(A,BC,DE,HL) 
I=LOC$(A$, [N1,N2]) 



# - Fortran Source Code Included 
+ - Assembler Source Code Included 



A$,B$ are string names using the convention of a $ 

in the last position of the name as a reminder 
that this is the name used when referencing 
string variables. 

N1,N2,N3,N4 are numeric integers (1,2,3. ...n) that are 

generally dimension subscripts of an array (of 
strings). In several cases these represent 
action codes, string termination values, 
position values etc. 

PI are either A$-type string variable names or 

Nl-type integer variable names as defined 
above. 

S$ is a uniquely defined character string 

variable consisting of multiple optional 
parameters. This type of string is used to 
exchange file parameter information, such as 
the file assignment data as follows: 
NEWNAME . TXT=OLDNAME . TXT/L . 

A,BC r DE,HL are integer variables representing the values 

of the respective registers being passed to 
CP/M. 
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The Software Cross Reference Guide 



LIST 



FORMAL SERIES SORT 



DEMO 



FILE routines 



VER$ 

DEFD$ 

DEFS$ 


X 
X 
X 


X 
X 


X 
X 
X 


X 
X 


X 
X 


DEFT$ 

STRIP$ 

UPPER$ 


X 
X 


X 
X 
X 


X 
X 


X 
X 
X 


X 


LOWER $ 

CMD$ 

MAKE$ 


X 


X 
X 


X 
X 


X 
X 


X 


MERGE $ 
RIGHT$ 
MID$ 




X 
X 
X 


X 


X 


X 
X 
X 


LEFT$ 
SWAP$ 
IEOS$ 


X 


X 
X 


X 


X 


X 


LEN$ 
IDEN$ 
MATCH $ 


X 
X 


X 
X 


X 
X 
X 


X 
X 
X 


X 
X 


NVAL$ 
LOOK$ 
NFORM$ 


X 
X 


X 
X 
X 


X 


X 
X 


X 


CHAIN$ 

DIR$ 

REN$ 


X 


X 
X 


X 


X 


X 
X 
X 


KILL$ 

SELCT$ 

RESET$ 




X 






X 


CPM$ 
LOC$ 













X 
X 
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User Comments and/or Problem Reporting Form 

The last page of this manual (The BUG Bit) is a 
convenient form upon which you may place you comments or 
criticisms. Should this form be missing, please feel free to 
send us your comments anyway , to: 



KEY BITS INC. 

P. 0. BOX 592293 

MIAMI, FL 33159 
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